home *** CD-ROM | disk | FTP | other *** search
/ Aminet 4 / Aminet 4 - November 1994.iso / aminet / dev / c / cweb31p9d.lha / CWeb / readme < prev    next >
Text File  |  1994-07-09  |  16KB  |  321 lines
  1.                             -*-Text-*-
  2. % This file is part of CWEB.  (Set TAB to 8 spaces.)
  3. % The CWEB programs by Silvio Levy are based on programs by D. E. Knuth.
  4. % They are distributed WITHOUT ANY WARRANTY, express or implied.
  5. % This README file was last updated July 9, 1994 by Andreas Scherer
  6.  
  7. % This is CWEB, Version 3.1 [p9d] of July 2, 1994, 19:30:00.
  8. % This package includes CWEB, Version 3.1 of November 1993.
  9.  
  10. % Copyright (C) 1987,1990,1993 Silvio Levy and Donald E. Knuth
  11. % Copyright (C) 1991-1993 Hans-Hermann Bode
  12. % Copyright (C) 1992 Klaus Guntermann
  13. % Copyright (C) 1991,1993 Carsten Steger
  14. % Copyright (C) 1993,1994 Andreas Scherer
  15.  
  16. % Permission is granted to make and distribute verbatim copies of this
  17. % document provided that the copyright notice and this permission notice
  18. % are preserved on all copies.
  19.  
  20. % Permission is granted to copy and distribute modified versions of this
  21. % document under the conditions for verbatim copying, provided that the
  22. % entire resulting derived work is distributed under the terms of a
  23. % permission notice identical to this one.
  24.  
  25. % Please send comments, suggestions, etc., concerning the original CWEB
  26. % implementation to levy@geom.umn.edu.
  27. % Please send comments, suggestions, etc., related to changes specific
  28. % for MSDOS and TURBOC to Hans-Hermann Bode,
  29. % hhbode@@dosuni1.rz.uni-osnabrueck.de or HHBODE@@DOSUNI1.BITNET.
  30. % Please send comments, suggestions, etc., related to changes specific
  31. % for AMIGA and SAS/C, and catalog translations to Andreas Scherer,
  32. % Abt-Wolf-Straße 17, 96215 Lichtenfels, Germany, [++49](0)9571/2013.
  33.  
  34. This is the ANSI-C/C++ implementation of Silvio Levy's and Donald E.
  35. Knuth's CWEB system, compiled and provided with changefiles for ANSI-C
  36. and a makefile for Turbo C++ by Hans-Hermann Bode, including additional
  37. changes to improve support of ANSI-C compilers and a makefile for C89
  38. by Klaus Guntermann, and including additional changes for full support
  39. of ANSI-C compilers and a makefile for SAS/C 6.x on the AMIGA by Andreas
  40. Scherer.  Additional features are described below.
  41.  
  42. Note that the changes for the Turbo-C++ compiler are made conditional
  43. (they will become effective only if the symbol __TURBOC__ is defined,
  44. which automatically is the case when compiled with Turbo C++), so users
  45. of other systems with ANSI-C compilers might be able to compile the
  46. sources without editing.
  47.  
  48. Note that the changes for the AMIGA and SAS/C 6.x compiler support are
  49. made conditional (they will become effective only if the symbol _AMIGA
  50. is defined, which automatically is the case when compiled with the SAS/C
  51. compiler).
  52.  
  53. AMIGA patch 3.1 [p9d] was evaluated on July 1, 1994, by Andreas Scherer
  54. and Burkhard Schmitt of Bayreuth University with CC and GCC on a HP Apollo
  55. workstation and a Sun 4 workstation and a SGI workstation.
  56. AMIGA patch 3.1 [p9d] was evaluated on July 2, 1994, by Andreas Scherer
  57. with Borland C++ version 3.1 on a PC without any problems.
  58. There are new versions of both MAKEFILE.PC and MAKEFILE.UNIX providing
  59. better support for the internal dependencies.
  60.  
  61. This directory contains the following files from the original CWEB
  62. distribution (`.' denotes the current directory):
  63.  
  64. ./makefile.unix        extended makefile from the original distribution
  65. ./readme        extended readme file from the original distribution
  66. ./common.h        header file to be included in ctangle.w and cweave.w
  67. ./common.w        common code for ctangle and cweave
  68. ./comm-man.ch        change file for the complete documentation
  69. ./comm-vms.ch        example change file for VAX/VMS (not incorporated)
  70. ./ctangle.w        the tangle processor
  71. ./ctang-man.ch        change file for the complete documentation
  72. ./ctang-vms.ch        example change file for VAX/VMS (not incorporated)
  73. ./cweave.w        the weave processor
  74. ./cweav-man.ch        change file for the complete documentation
  75. ./cweav-vms.ch        example change file for VAX/VMS (not incorporated)
  76. ./cweb.1        manual page (nroff format)
  77. ./cweb.el        elisp file for GNU Emacs
  78. ./cwebman.tex        the user manual
  79. ./prod.w        production rules to be included in cweave.w
  80. ./wmerge.w        WEB-like file merger by Silvio Levy
  81. ./examples        directory containing examples of CWEB programming
  82. ./examples/extex.w    - spellchecking filter for TeX and CWEB by Don Knuth
  83. ./examples/kspell.el    - Emacs interface to extex/wordtest
  84. ./examples/makefile.org    - generic makefile for CWEB applications
  85. ./examples/oemacs.el    - Emacs interface to oemacs
  86. ./examples/oemacs.w    - non-portable example program for OpenWindows
  87. ./examples/readme.org    - readme file from the examples directory
  88. ./examples/treeprint.w    - tree-structured directory lister by Norman Ramsey
  89. ./examples/wc.w        - UNIX word-count utility
  90. ./examples/wordtest.w    - spellchecker by Don Knuth
  91. ./examples/xlib_types.w    - include file for XView programs
  92. ./examples/xview_types.w  mega-ditto
  93. ./macros/cwebmac.tex    macros for formatting
  94.  
  95. The following change files for AMIGA and PC provided with the original
  96. distribution are incorporated into the present change files in full (well,
  97. almost full: the memory restrictions for MSDOS had not to be met for UNIX
  98. and AMIGA, so throw them away) detail by preprocessor conditionals and
  99. are no longer present in this distribution:
  100.  
  101. ./comm-amiga.ch
  102. ./comm-pc.ch
  103. ./ctang-amiga.ch
  104. ./ctang-pc.ch
  105. ./cweav-amiga.ch
  106. ./cweav-pc.ch
  107.  
  108. The following files were added to this distribution by various contributors:
  109.  
  110. general:
  111. ./comm-p.h        wmerged product of common.h and comm-p.hch
  112. ./comm-p.hch        change file for common.h
  113. ./common.c        ctangled product of common.w and common.ch
  114. ./common.ch        change file for common.w
  115. ./ctangle.c        ctangled product of ctangle.w and ctangle.ch
  116. ./ctangle.ch        change file for ctangle.w
  117. ./cweave.ch        change file for cweave.w
  118. ./cweb.man        manual page (ASCII format)
  119. ./cweb31.readme        description file from the AmiNet distribution
  120. ./cwebmang.ch        change file for cwebman.tex
  121. ./wmerge.c        ctangled product from wmerge.w and wmerge.ch
  122. ./wmerge.ch        change file for wmerge.w
  123. ./examples/cct.w    program to translate between character code tables
  124. ./examples/commonwords.w program to count word frequencies in text files
  125. ./examples/extex.ch    change file for extex.w
  126. ./examples/matrix.wpp    C++ program to invert complex 4x4 matrices
  127. ./examples/primes.w     program to print the first 1000 prime numbers
  128. ./examples/sample.w     program to produce random numbers
  129. ./examples/treeprint.ch    change file for treeprint.w
  130. ./examples/wc.ch    change file for wc.w
  131. ./examples/wordtest.ch    change file for wordtest.w
  132. ./include/ecma94.w    Transliteration table for Latin-1
  133. ./include/hp8.w        Transliteration table for HP Roman 8
  134. ./include/mac8.w    Transliteration table for Macintosh 8-bit font
  135. ./include/pc850.w    Transliteration table for Codepage 850
  136. ./macros/ccwebmac.tex    beautifications for cwebmac.tex
  137. ./macros/ecma94.tex    Umlauts and special characters for Latin-1
  138. ./macros/gcwebmac.tex    German captions in addition to cwebmac.tex
  139. ./macros/hp8.tex    Umlauts and special characters for HP Roman 8
  140. ./macros/mac8.tex    Umlauts and special characters for Macintosh 8-bit
  141. ./macros/pc850.tex    Umlauts and special characters for Codepage 850
  142.  
  143. special for PC users by Hans-Hermann Bode modified by Andreas Scherer:
  144. ./makefile.pc        makefile for Turbo C++
  145.  
  146. special for users of cc, c89, gcc or other ANSI C compilers for UNIX
  147. by Klaus Guntermann modified by Andreas Scherer according to the original
  148. makefile from the CWEB distribution:
  149. ./makefile.unix        makefile for cc, c89, gcc, ...
  150.  
  151. special for AMIGA users by Andreas Scherer:
  152. ./makefile.amiga    makefile for SAS/C compiler 6.0 and up
  153. ./arexx/compile.ced    ARexx script to start SAS/C 6.x from CED (V3.5+)
  154. ./arexx/start_web.ced    ARexx script to start cweave and ctangle from CED
  155. ./arexx/catalogs/cweb_arexx.cd Catalog description for German defaults
  156. ./arexx/catalogs/cweb_arexx.e.ct Catalog translation for English users
  157. ./arexx/catalogs/english/cweb_arexx.catalog Message catalog for English users
  158. ./bin/ctangle        executable ctangle processor, Amiga version
  159. ./bin/cweave        executable cweave processor, Amiga version
  160. ./bin/wmerge        executable WEB merge program, Amiga version
  161. ./bin/catalogs/cweb.cd    Catalog description for English defaults
  162. ./bin/catalogs/cweb.d.ct Catalog translation for German users
  163. ./bin/catalogs/cweb.h    header file with the English defaults
  164. ./bin/catalogs/gcweb.h    header file with the German defaults
  165. ./bin/catalogs/deutsch/cweb.catalog Message catalog for German users
  166. ./examples/makefile    makefile for SAS/C compiler 6.0 and up
  167.  
  168. The additional files with extensions .h, .w, .tex, and .c are
  169. reproducable from the other sources by means of an executable
  170. wmerge, ctangle, cweave, and an ANSI-C compiler.
  171.  
  172. Before starting, you should run cwebmang.tex (needs cwebmac.tex and
  173. ccwebmac.tex and gcwebmac.tex!) through TeX and print out the manual.
  174.  
  175. Make sure, that the files you got are in proper format (if you took
  176. them from a ZIP archive, line ends might still contain carriage return
  177. and linefeed characters, which may not be appropriate for your operating
  178. system).
  179.  
  180. How to create the binaries:
  181.  
  182. 1.  Rename `makefile.amiga' to `makefile' or `smakefile', for use with
  183. SMAKE.  If you want to install the package on a UNIX system with CC, C89 or
  184. GCC, use `makefile.unix' instead.  If you want to install the package on
  185. MSDOS with TURBOC, use `makefile.pc' instead.
  186.  
  187. 2.  Check the entries in the makefile for local conditions like a different
  188. compiler name or additional compiler options you want to use.  Check also
  189. the other lines in the makefile so that all directory definitions are set
  190. properly for your local system configuration.
  191.  
  192. 3.  Touch common.c, ctangle.c, and wmerge.c to make them up-to-date.
  193. To make ctangle, cweave and the wmerge processor say `make progs'; this
  194. should  produce actions similar to the following, possibly with harmless
  195. warning messages from the compiler (there won't be any if you use the
  196. SAS/C 6.x compiler, except some optimizer messages), and e.g., the options
  197. and the name of the compiler may be as modified in the makefile:
  198.  
  199.     sc $(CFLAGS) ctangle.c
  200.     sc $(CFLAGS) common.c
  201.     slink FROM $(OBJS) ctangle.o TO ctangle LIB $(LIBS)
  202.     ctangle cweave cweave.ch
  203.     sc $(CFLAGS) cweave.c
  204.     slink FROM $(OBJS) cweave.o TO cweave LIB $(LIBS)
  205.     sc $(CFLAGS) link wmerge.c
  206.  
  207. or on UNIX systems
  208.  
  209.     cc -g -w -c ctangle.c
  210.     cc -g -w -DCWEBINPUTS=\"/usr/local/lib/cweb\" -c common.c
  211.     cc -g -o ctangle ctangle.o common.o 
  212.     ./ctangle cweave
  213.     cc -g -w -c cweave.c
  214.     cc -g -w -o cweave cweave.o common.o
  215.     cc -g -w -o wmerge wmerge.c
  216.  
  217. To get some reassurance that things are OK, you can say `make cautiously',
  218. which ensures that ctangle will reproduce itself.  (Otherwise the source
  219. files common.w and ctangle.w won't actually have been used.)
  220.  
  221. To install cweave, ctangle, wmerge, cwebmac.tex, ccwebmac.tex, and
  222. gcwebmac.tex, the manual page, an emacs macro file, and the ARexx script
  223. files and associated language catalogs, say `make install'.  You may also
  224. decide to move the files manually to their proper places.  See the Makefile
  225. for details, what to move, and for suggestions, where to move it.  And see
  226. the ARexx script itself for details how to make use of it from CygnusEd
  227. Professional Editor.
  228.  
  229. If you want to recompile the programs for another system, you should take a
  230. look inside the change files common.ch, comm-p.hch, ctangle.ch, and
  231. cweave.ch.  Some of the entries marked with "SYSTEM DEPENDENCIES" may need
  232. modifications appropriate for the target system.  All change files are set
  233. up to work for Amiga, PC, and UNIX identically, so no further changes will
  234. be needed if you use on of these systems.
  235.  
  236. Incidentally, if you try the recompilation with another compiler for
  237. another system, you may have no luck without changing the sources.
  238. In this case, it is necessary to do all the required changes in the
  239. .c file first, until you can compile ctangle.c and common.c.  But it
  240. is necessary then, to add the same modifications to the change file
  241. (never make any changes to the .w files!).  Finally processing ctangle.w
  242. and the extended change file for ctangle with the modified ctangle will
  243. create the same contents as the modifications made by hand.  If such
  244. changes are needed for a common compiler, please notify the authors
  245. about this and send the extended changes.
  246.  
  247. Do not edit one of the .w files under any circumstances.  Do all
  248. modifications in the associated .ch files, but keep in mind that
  249. you'll need a working ctangle processor to generate the updated .c
  250. files.  And beware:  CWEB version 3 needs a ctangle and cweave with
  251. `longest_name==1000', so any older version with `longest_name==400' will
  252. fail!  Furthermore, do not edit common.h, prod.w, or cwebmac.tex.
  253. Make your modifications to comm-p.hch and add change files for the
  254. other two.  To incorporate the changes you will need a working wmerge
  255. program.  This will be prepared when ctangle and cweave are created.
  256. There is a tangled wmerge.c also in case you don't have a working
  257. ctangle processor so far.  However, feel free to make changes to the
  258. macroc files ccwebmac.tex and gcwebmac.tex in the ./macros subdirectory.
  259.  
  260. If you want a full documentation of the tangle and weave programs,
  261. type `make docs'.  The documentation created will include all changes
  262. introduced by the .ch files.  To get a list of all catalog strings, you
  263. should also print the file ./bin/catalogs/cweb.h with the original set
  264. of output strings and possibly ./bin/catalogs/cweb.d.ct for a clue to
  265. translations.  If you want to use CWEB on a system without localization,
  266. there is the file ./bin/catalogs/gcweb.h, so German program versions
  267. can be created easily.
  268.  
  269. To delete all intermediate files created in the make processes say
  270. `make clean'.  You will be left with the files in this distribution.
  271.  
  272. The weave and tangle processors as well as wmerge now recognize a
  273. CWEBINPUTS environment variable.  When an include file name (argument
  274. to the @i command) can not be found in the current directory or in the
  275. absolute path, a multi-path search is performed.  CWEBINPUTS---if not
  276. empty---may contain a list of search path names, delimited by
  277. PATH_SEPARATORs, i.e., commas.  The current directory is represented
  278. by an empty path entry, but it is searched first anyway.  Device names
  279. must end in an DEVICE_SEPARATOR, i.e., colons.  Example for AmigaOS:
  280.  
  281.     setenv CWEBINPUTS "RAM:,CWEB:includes"
  282.  
  283. In the respective makefiles for AMIGA, UNIX and PC some decent defaults
  284. are set in the compile time constant CWEBINPUTS.
  285.  
  286. The tangle and weave processors of this implementation are able to
  287. process traditional C, ANSI C, and C++.  Note that ctangle always uses
  288. a default extension .c for its output file; this may not be appropriate
  289. for some C++ compilers, but you can work around this by supplying a third
  290. argument in the command line (see cwebman).
  291.  
  292. Patch level [p9b] of this implementation introduced localization to other
  293. languages than English.  All output strings of ctangle or cweave were
  294. replaced by variable references to an array AppStrings in cweb.h, set to the
  295. English defaults at startup time.  This works for all systems and compilers
  296. in a compatible way.  However, version 2.1 of the AMIGA operating system
  297. introduced the use of language catalogs, thus enabling programs and
  298. applications to be inherently multilingual without recompilation.  To
  299. activate this feature, you only have to install AmigaOS 2.1/3.0.  A German
  300. catalog is already there at the right place (./bin/catalogs/deutsch), so
  301. ctangle and cweave will great you in German, if you start them from their
  302. home directory ./bin and if your system default language is German.
  303. Catalog translations for other languages can easily be installed.
  304.  
  305. Patch level [p9d] of this implementation introduced dynamic memory allocation
  306. for all internal arrays except for `flags[256]'.  By this method both ctangle
  307. and cweave can be compiled in the `NEAR' data segment, so on the AMIGA they
  308. can be made `resident', i.e., they can reside in RAM and don't have to be
  309. loaded from disk after the first time.
  310.  
  311. Patch level [p9d] of this implementation introduced an ARexx communication
  312. facility between CWEB (i.e., ctangle and cweave) and the `Message Browser'
  313. SCMSG, included in the SAS/C 6.X development system.  If you run CWEB with
  314. the `+m' option, any warnings or error messages will be displayed in the
  315. window of SCMSG.  The default setting is `off'.  You can control the
  316. behaviour of this feature by setting the environment variable SCMSGOPT
  317. to a string with any legal command line options for SCMSG as described
  318. in the documentation provided with the compiler package by SAS Institute.
  319. If the environment variable is not set, the default behaviour of SCMSG
  320. will be used.
  321.